home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1996 February / EnigmA AMIGA RUN 04 (1996)(G.R. Edizioni)(IT)[!][issue 1996-02][Skylink CD III].iso / earcd / midi / magicmod.lha / PTReplay.doc < prev    next >
Text File  |  1995-11-08  |  17KB  |  649 lines
  1. TABLE OF CONTENTS
  2.  
  3. ptreplay.library/PTFade
  4. ptreplay.library/PTFreeMod
  5. ptreplay.library/PTGetChan
  6. ptreplay.library/PTGetPri
  7. ptreplay.library/PTGetSample
  8. ptreplay.library/PTInstallBits
  9. ptreplay.library/PTLoadModule
  10. ptreplay.library/PTOffChannel
  11. ptreplay.library/PTOnChannel
  12. ptreplay.library/PTPatternData
  13. ptreplay.library/PTPatternPos
  14. ptreplay.library/PTPause
  15. ptreplay.library/PTPlay
  16. ptreplay.library/PTResume
  17. ptreplay.library/PTSetPos
  18. ptreplay.library/PTSetPri
  19. ptreplay.library/PTSetupMod
  20. ptreplay.library/PTSetVolume
  21. ptreplay.library/PTSongLen
  22. ptreplay.library/PTSongPattern
  23. ptreplay.library/PTSongPos
  24. ptreplay.library/PTStartFade
  25. ptreplay.library/PTStop
  26. ptreplay.library/PTUnloadModule
  27. ptreplay.library/PTFade                               ptreplay.library/PTFade
  28.  
  29.    NAME
  30.         PTFade -- Let a module "slide away" before it's stopped (V2)
  31.  
  32.    SYNOPSIS
  33.         PTFade(module,speed)
  34.                 A0     D0
  35.  
  36.         void PTFade(struct Module *, UBYTE);
  37.  
  38.    FUNCTION
  39.         This function does smooth vol slidedown until volume reaches zero,
  40.         then the module is stoped and the function returns. The speed is
  41.         given in the number of "vblanks" (ie CIA timeouts because it uses
  42.         CIA timing instead of vblank timing) between each step.
  43.  
  44.    INPUTS
  45.         module - module that is to be stoped.
  46.         speed - fading speed.
  47.  
  48.    SEE ALSO
  49.         PTStartFade()
  50.  
  51. ptreplay.library/PTFreeMod                         ptreplay.library/PTFreeMod
  52.  
  53.    NAME
  54.         PTFreeMod -- Deallocates a module create with PTSetupMod. (V4)
  55.  
  56.    SYNOPSIS
  57.         PTFreeMod(Module)
  58.                   A0
  59.  
  60.         void PTFreeMod(struct Module *);
  61.  
  62.    FUNCTION
  63.         This function will free all memory allocated by the PTSetupMod
  64.         function.
  65.  
  66.    INPUTS
  67.         Module - a module returned by PTSetupMod().
  68.  
  69.    SEE ALSO
  70.         PTSetupMod()
  71.  
  72. ptreplay.library/PTGetChan                         ptreplay.library/PTGetChan
  73.  
  74.    NAME   
  75.         PTGetChan -- Return wich channels ptreplay owns. (V6)
  76.  
  77.    SYNOPSIS
  78.         Chans=PTGetChan()
  79.         D0
  80.  
  81.         BYTE PTGetChan(void);
  82.  
  83.    FUNCTION
  84.         This function returns an array there bit 0 is set if it owns channel
  85.         0, bit 1 is set if it owns channel 1 and so on.
  86.  
  87.    RESULT
  88.         Chans - An bitarray telling you wich channel it owns.
  89.  
  90.    SEE ALSO
  91.  
  92. ptreplay.library/PTGetPri                           ptreplay.library/PTGetPri
  93.  
  94.    NAME   
  95.         PTGetPri -- Return the priority currently used. (V5)
  96.  
  97.    SYNOPSIS
  98.         Pri=PTSetPri()
  99.         D0
  100.         BYTE PTSetPri(void);
  101.  
  102.    FUNCTION
  103.         This function returnes the current priority on wich ptreplay hold
  104.         it's channels.
  105.  
  106.    RESULT
  107.         Pri - The priority currently used by ptreplay.
  108.  
  109.    SEE ALSO
  110.         PTSetPri()
  111.  
  112. ptreplay.library/PTGetSample                     ptreplay.library/PTGetSample
  113.  
  114.    NAME   
  115.         PTGetSample -- Return info on a sample. (V6)
  116.  
  117.    SYNOPSIS
  118.         Sam=PTGetSample(Module,Num);
  119.         D0              A0     D0
  120.  
  121.         struct PTSample *PTGetSample(struct Module *,WORD);
  122.  
  123.    FUNCTION
  124.         This function collects info about the given sample-number.
  125.  
  126.         it returns the folowing structure:
  127.         struct PTSample
  128.         {
  129.             UBYTE Name[22];    /* Null terminated string with samplename */
  130.             UWORD Length;      /* Sample length in words */
  131.             UBYTE FineTune;    /* FineTune of sample in lower 4 bits */
  132.             UBYTE Volume;      /* Volume of sample */
  133.             UWORD Repeat;      /* Repeat start in number of words */
  134.             UWORD Replen;      /* Repeat length in number of words */
  135.         };
  136.  
  137.    INPUTS
  138.         Module - Pointer to a loaded module
  139.         Num    - Number of the sample you whant info about. MUST BE 0-31
  140.  
  141.    RESULT
  142.         Sam - Info about the given sample.
  143.  
  144.    SEE ALSO
  145.  
  146. ptreplay.library/PTInstallBits                 ptreplay.library/PTInstallBits
  147.  
  148.    NAME
  149.         PTInstallBits -- Defines what to be signaled at and how (V4)
  150.  
  151.    SYNOPSIS
  152.         PTInstallBits(Module, Restart, Pos, Row, Fade);
  153.                       A0      D0       D1   D2   D3
  154.  
  155.         void PTInstallBits(struct Module *, BYTE, BYTE, BYTE, BYTE);
  156.  
  157.    FUNCTION
  158.         This function is used to inform ptreplay which signals to send to
  159.         this task at the given positions. Currently it can only be set up to
  160.         signal one task/module (the one calling this function) this may
  161.         however change in future. A signalbit of -1 tells ptreplay not to
  162.         signal you at that specific location.
  163.  
  164.    INPUTS
  165.         Module - module to use the given signals
  166.         Restart - Bit to set when a module restarts from beginning or -1 for
  167.             no signal.
  168.         Pos - Bit to set when moving to next position or -1 for no signal
  169.         Row - Bit to set when moving to next row in pattern or -1 for no
  170.             signal.
  171.         Fade - Bit to set when PTStartFade is done and have stoped module or
  172.             -1 for no signal.
  173.  
  174.    EXAMPLE
  175.         /* This will set signalbit 4 when the module restarts */
  176.         PTInstallBits(Module, 4, -1, -1, -1);
  177.  
  178.         /* This will set signalbit 0 when startfade has stopped the module */
  179.         PTInstallBits(Module, -1, 1, -1, 0);
  180.  
  181.    SEE ALSO
  182.         PTStartFade()
  183.  
  184. ptreplay.library/PTLoadModule                   ptreplay.library/PTLoadModule
  185.  
  186.    NAME
  187.         PTLoadModule -- Load a module.
  188.  
  189.    SYNOPSIS
  190.         module=PTLoadModule(name)
  191.           D0                A0
  192.  
  193.         struct module *PTLoadModule(STRPTR);
  194.  
  195.    FUNCTION
  196.         The named file is loaded into chip-mem and if it's identified as an
  197.         protracker module, a module control structure is created and then
  198.         returned to you for usage in the other functions like PTPlay
  199.  
  200.    INPUTS
  201.         name - name of a module file.
  202.  
  203.    RESULT
  204.         module - a pointer to a module control structure or NULL if the
  205.             module couldn't be loaded.
  206.  
  207.    SEE ALSO
  208.         PTSetupMod(), PTUnloadModule()
  209.  
  210. ptreplay.library/PTOffChannel                   ptreplay.library/PTOffChannel
  211.  
  212.    NAME   
  213.         PTOffChannel -- Turns off one or more channels. (V5)
  214.  
  215.    SYNOPSIS
  216.         PTStartFade(Module, Channel)
  217.                     A0      D0
  218.  
  219.         void PTStartFade(struct Module *, BYTE);
  220.  
  221.    FUNCTION
  222.         This function is used to turn one or more channels off in order to
  223.         stop ptreplay producing sound for that channel. Note that this isn't
  224.         a nested command and turning off a channel that is already off will
  225.         give you strange results and is _not_ recomended.
  226.  
  227.    INPUTS
  228.         Module - Module to select channels for.
  229.         Channel - Channels to be turned off.
  230.  
  231.    RESULT
  232.  
  233.    EXAMPLE
  234.  
  235.    NOTES
  236.  
  237.    BUGS
  238.         Turning a channel off will not release it to be used by other
  239.         programms via audio.device.
  240.  
  241.    SEE ALSO
  242.         PTOnChannel()
  243.  
  244. ptreplay.library/PTOnChannel                     ptreplay.library/PTOnChannel
  245.  
  246.    NAME   
  247.         PTOnChannel -- Turns on one or more channels. (V5)
  248.  
  249.    SYNOPSIS
  250.         PTStartFade(Module, Channel)
  251.                     A0      D0
  252.  
  253.         void PTStartFade(struct Module *, BYTE);
  254.  
  255.    FUNCTION
  256.         This function is used to turn one or more channels on in order for
  257.         ptreplay to produce sound for that channel. Note that this isn't
  258.         a nested command and turning on a channel that is already on will
  259.         give you strange results.
  260.  
  261.    EXAMPLE
  262.        ;Turn on all 4 channels
  263.        PTOnChannel(Mod, $f);
  264.  
  265.        ;Turn on channel 0,1 & 2
  266.        PTOnChannel(Mod, &7);
  267.  
  268.    INPUTS
  269.         Module - Module to select channels for.
  270.         Channel - Channels to be turned on.
  271.  
  272.    SEE ALSO
  273.         PTOffChannel()
  274.  
  275. ptreplay.library/PTPatternData                 ptreplay.library/PTPatternData
  276.  
  277.    NAME
  278.         PTPatternData -- Returns the adress of specified pattern/row (V4)
  279.  
  280.    SYNOPSIS
  281.         RowData=PTPatternData(Module, PatternNum, RowNum)
  282.         D0                    A0      D0          D1
  283.  
  284.         APTR PTPatternData(struct Module *, UBYTE, UBYTE);
  285.  
  286.    FUNCTION
  287.         This function returns a pointer to the given row in the specified
  288.         pattern.
  289.  
  290.    INPUTS
  291.         Module     - Pointer to the module you which to examine.
  292.         PatternNum - The pattern (0-127) you want to examine.
  293.         RowNum      - And finaly which row (0-63) to examine.
  294.  
  295.    RESULT
  296.         RowData - A pointer to the given position
  297.  
  298. ptreplay.library/PTPatternPos                   ptreplay.library/PTPatternPos
  299.  
  300.    NAME
  301.         PTPatternPos -- Returns the patternrow currently playing (V4)
  302.  
  303.    SYNOPSIS
  304.         Row=PTPatternPos(module)
  305.         D0               A0
  306.  
  307.         UBYTE PTPatternPos(struct Module *);
  308.  
  309.    FUNCTION
  310.         Returns the row in the pattern that it is currently being played.
  311.  
  312.    INPUTS
  313.         module - A module that is currently being played.
  314.  
  315.    RESULT
  316.         Row - The row (0-63 $00-$40) that is being played.
  317.  
  318. ptreplay.library/PTPause                             ptreplay.library/PTPause
  319.  
  320.    NAME
  321.         PTPause -- pauses a module.
  322.  
  323.    SYNOPSIS
  324.         PTPause(module)
  325.                 A0
  326.  
  327.         void PTPause(struct Module *);
  328.  
  329.    FUNCTION
  330.         Pause this module, remembering the position so that you can restart
  331.         it later. All sound is turned off.
  332.  
  333.    INPUTS
  334.         module - pointer to module control structure.
  335.  
  336.    NOTES
  337.         All channels are still allocated at the same priority after this
  338.         functions has returned so it's vise to lower the priority to -128
  339.         before calling this function.
  340.  
  341.    SEE ALSO
  342.         PTResume()
  343.  
  344. ptreplay.library/PTPlay                               ptreplay.library/PTPlay
  345.  
  346.    NAME
  347.         PTPlay -- Plays a module
  348.  
  349.    SYNOPSIS
  350.         PTPlay(module)
  351.                 A0
  352.  
  353.         void PTPlay(struct Module *);
  354.  
  355.    FUNCTION
  356.         Start playing the module from the beginning. If this module already
  357.         was playing, it starts over from the beginning.
  358.  
  359.    INPUTS
  360.         module - pointer to module control structure.
  361.  
  362.    BUGS
  363.         It is not yet supported to call this function while another module
  364.         is playing.
  365.         If another module is playing, it will be stopped and this will be
  366.         played instead. (V5)
  367.  
  368.    SEE ALSO
  369.         PTStop()
  370.  
  371. ptreplay.library/PTResume                           ptreplay.library/PTResume
  372.  
  373.    NAME
  374.         PTResume -- restarts a paused module.
  375.  
  376.    SYNOPSIS
  377.         PTResume(module)
  378.                  A0
  379.  
  380.         void PTResume(struct Module *);
  381.  
  382.    FUNCTION
  383.         Resume playing this module, after it was paused. If it was not
  384.         paused then nothing happens. Becasue PTPause&PTResume doesn't nest
  385.         will the module continue after the first call to PTResume.
  386.  
  387.    INPUTS
  388.         module - pointer to module control structure.
  389.  
  390.    SEE ALSO
  391.         PTPause()
  392.  
  393. ptreplay.library/PTSetPos                           ptreplay.library/PTSetPos
  394.  
  395.    NAME   
  396.         PTSetPos -- Changes the position for a playing module. (V5)
  397.  
  398.    SYNOPSIS
  399.         PTSetPos(Module, Pos)
  400.                  A0      D0
  401.  
  402.         void PTSetPos(struct Module *, UBYTE);
  403.  
  404.    FUNCTION
  405.         This function changes the position which we are playing to the new
  406.         one.
  407.  
  408.    INPUTS
  409.         Module - Module to change pos in.
  410.         Pos - The new position 0 - SongLen-1
  411.  
  412.    SEE ALSO
  413.         PTSongPos(), PTSongLen()
  414.  
  415. ptreplay.library/PTSetPri                           ptreplay.library/PTSetPri
  416.  
  417.    NAME
  418.         PTSetPri -- Sets the priority that ptreplay should use. (V5)
  419.  
  420.    SYNOPSIS
  421.         PTSetPri(Pri)
  422.                  D0
  423.  
  424.         void PTSetPri(BYTE);
  425.  
  426.    FUNCTION
  427.         This function changes the priority on wich ptreplay hold it's
  428.         channels. It deafults to -128 and is also reset to -128 every time
  429.         the library is closed (OpenCnt==NULL).
  430.  
  431.         NOTE for V6: Now the channels are completly freed when the library
  432.         is closed.
  433.  
  434.    INPUTS
  435.         Pri - The new priority
  436.  
  437.    SEE ALSO
  438.         PTGetPri()
  439.  
  440. ptreplay.library/PTSetupMod                       ptreplay.library/PTSetupMod
  441.  
  442.    NAME
  443.         PTSetupMod -- Creates a control structure for a loaded module. (V4)
  444.  
  445.    SYNOPSIS
  446.         Module = PTSetupMod(LoadedMod);
  447.         D0                  A0
  448.  
  449.         struct Module *PTSetupMod(APTR);
  450.  
  451.    FUNCTION
  452.         This function will allocate a module control structure and intilize
  453.         it using an already loaded module file in order to use in with
  454.         ptreplay.
  455.  
  456.    INPUTS
  457.         LoadedMod - An pointer to an already loaded module.
  458.  
  459.    RESULT
  460.         Module - A module control structure ready to use.
  461.  
  462.    EXAMPLE
  463.         /* This routine will do the same thing as PTLoadMod */
  464.         BPTR File;
  465.         APTR Mod;
  466.         int Len;
  467.         struct Module *Module;
  468.  
  469.         File=Open("mod.module",MODE_OLDFILE))
  470.         Seek(File, 0l, OFFSET_END);
  471.         Len=Seek(File, 0l, OFFSET_BEGINNING);
  472.  
  473.         Mod=AllocMem(Len, MEMF_CHIP);
  474.         Read(File, Mod, Len);
  475.         Close(File);
  476.         Module=PTSetupMod(Mod);
  477.  
  478.    NOTES
  479.         1. The module MUST already be located in chip mem.
  480.         2. The module MUST be valid while the module is going to be used.
  481.         Both may change in future.
  482.  
  483.    SEE ALSO
  484.         PTFreeMod()
  485.  
  486. ptreplay.library/PTSetVolume                     ptreplay.library/PTSetVolume
  487.  
  488.    NAME   
  489.         PTSetVolume -- Sets the base volume (V3)
  490.  
  491.    SYNOPSIS
  492.         PTSetVolume(module,volume)
  493.                     A0     D0
  494.  
  495.         void PTSetVolume(struct Module *, UBYTE);
  496.  
  497.    FUNCTION
  498.         This function will change the base volume that ptreplay uses to
  499.         calculate the "real" volume for the specified module.
  500.         
  501.         The new volume is first multiplied by this value and then shifted
  502.         right 6 steps.
  503.  
  504.    INPUTS
  505.         module - pointer to module.
  506.         speed - new volume  0-64 ($00-$40)
  507.  
  508.    SEE ALSO
  509.         Fade(), StartFade().
  510.  
  511. ptreplay.library/PTSongLen                         ptreplay.library/PTSongLen
  512.  
  513.    NAME
  514.         PTSongLen -- returns songlength (V4)
  515.  
  516.    SYNOPSIS
  517.         Len=PTSongLen(module)
  518.         d0            a0
  519.  
  520.         UBYTE PTSongLen(struct Module *);
  521.  
  522.    FUNCTION
  523.         This funktion returns the length of the module in positions. This
  524.         is the same value as Length in ProTracker and means that it will
  525.         play until position Len-1.
  526.  
  527.    INPUTS
  528.         module - The module whos length you which to now.
  529.  
  530.    RESULT
  531.         Len - Number of positions in module
  532.  
  533. ptreplay.library/PTSongPattern                 ptreplay.library/PTSongPattern
  534.  
  535.    NAME   
  536.         PTSongPattern -- Returns pattern at a given position (V4)
  537.  
  538.    SYNOPSIS
  539.         PatNum=PTSongPattern(module, pos)
  540.         D0                   A0      D0
  541.  
  542.         UBYTE PTSongPattern(struct Module *,UWORD);
  543.  
  544.    FUNCTION
  545.         Returns the pattern number at a given position.
  546.  
  547.    INPUTS
  548.         Module - The module you want to examine
  549.         Pos - The position (0-127) you want to examine.
  550.  
  551.    RESULT
  552.         PatNum - A number (0-127) telling you which pattern is to be played.
  553.  
  554. ptreplay.library/PTSongPos                         ptreplay.library/PTSongPos
  555.  
  556.    NAME
  557.         PTSongPos -- Gives you the current song position (V4)
  558.  
  559.    SYNOPSIS
  560.         Pos=PTSongPos(module);
  561.         d0            A0
  562.  
  563.         UBYTE PTSongPos(struct Module *)
  564.  
  565.    FUNCTION
  566.         This function returns the position the module is curently playing.
  567.  
  568.    INPUTS
  569.         module - pointer to a module that is playing.
  570.  
  571.    RESULT
  572.         Pos - position 0 - (Length-1)
  573.  
  574.    SEE ALSO
  575.         PTSetPos()
  576.  
  577. ptreplay.library/PTStartFade                     ptreplay.library/PTStartFade
  578.  
  579.    NAME
  580.         PTStartFade -- Let a module fade-away before it's stopped (V4)
  581.  
  582.    SYNOPSIS
  583.         PTStartFade(Module, Speed)
  584.                     A0      D0
  585.  
  586.         void PTStartFade(struct Module *, UBYTE);
  587.  
  588.    FUNCTION
  589.         This function will also do a smooth volume slidedown in the same way
  590.         as PTFade does but it returns as soon as the fading has started
  591.         instead of when it is done. Currently the only way to notice when
  592.         the module is stoped is to setup a Fade bit using PTInstallBits and
  593.         check for that bit.
  594.  
  595.    INPUTS
  596.         Module - Module to be stoped.
  597.         Speed - fading speed.
  598.  
  599.    SEE ALSO
  600.         PTFade(), PTInstallBits()
  601.  
  602. ptreplay.library/PTStop                               ptreplay.library/PTStop
  603.  
  604.    NAME
  605.         PTStop -- Stops a module that is playing.
  606.  
  607.    SYNOPSIS
  608.         PTStop(module)
  609.                 A0
  610.  
  611.         void PTStop(struct Module *);
  612.  
  613.    FUNCTION
  614.         Stop playing the given module. If it wasn't playing, nothing
  615.         happens.
  616.  
  617.    INPUTS
  618.         module - pointer to module control structure.
  619.  
  620.    SEE ALSO
  621.         PTPlay(), PTFade()
  622.  
  623. ptreplay.library/PTUnloadModule               ptreplay.library/PTUnloadModule
  624.  
  625.    NAME
  626.         PTUnloadModule -- Deallocates a loaded module.
  627.  
  628.    SYNOPSIS
  629.         PTUnloadModule(module)
  630.                         A0
  631.  
  632.         void PTUnloadModule(struct Module *);
  633.  
  634.    FUNCTION
  635.         Deallocates a previsly loaded module, returning all it's resources
  636.         to the system.
  637.  
  638.    INPUTS
  639.         module - pointer to module control structure returned by LoadModule.
  640.  
  641.    BUGS
  642.         Does not check that module is stopped. If you call this function on
  643.         a module that is playing, you _will_ cause a System Failure. You
  644.         have been warned.
  645.  
  646.    SEE ALSO
  647.         PTFreeMod(), PTStop()
  648.  
  649.